home *** CD-ROM | disk | FTP | other *** search
/ Total Network Tools 2002 / NextStepPublishing-TotalNetworkTools2002-Win95.iso / Archive / Web Server / PHP.EXE / pear / PHPDoc / parser / PhpdocModuleParser.php < prev    next >
Encoding:
PHP Script  |  2001-02-18  |  5.2 KB  |  142 lines
  1. <?php
  2. /**
  3. * Extracts modules and their documentation from php code.
  4. * @author    Ulf Wendel <ulf.wendel@redsys.de>
  5. * @version 0.1alpha
  6. */
  7. class PhpdocModuleParser extends PhpdocConstantParser {
  8.  
  9.     /**
  10.     * Empty hash that shows the structure of a module.
  11.     * @var    array
  12.     */
  13.     var $emptyModule = array(
  14.     
  15.                                  "name"     => "",
  16.                                 "group"     => "",
  17.                                 "undoc"     => true,
  18.                                 
  19.                                 "functions" => array(),
  20.                                 "consts"    => array(),
  21.                                 "uses"      => array()
  22.                             );
  23.  
  24.     /**
  25.     * List of tags allowed within a module doc comment.
  26.     * @var    array    tagname => true
  27.     */                                                    
  28.     var $moduleTags = array(
  29.                             "module"        => true,
  30.                             "modulegroup"   => true,
  31.                             
  32.                             "access"        => true,
  33.                             
  34.                             "see"           => true,
  35.                             "link"          => true,
  36.                             
  37.                             "author"        => true,
  38.                             "copyright"     => true,
  39.                             
  40.                             "version"       => true,
  41.                             "since"         => true,
  42.                             
  43.                             "deprecated"    => true,
  44.                             "deprec"        => true,
  45.                             
  46.                             "brother"       => true,
  47.                             "sister"        => true,
  48.                             
  49.                             "exclude"       => true,
  50.                             
  51.                             "package"       => true,
  52.                             
  53.                             "magic"         => true,
  54.                             "todo"          => true
  55.                         );
  56.  
  57.     /**
  58.     * Hash of all module groups
  59.     *
  60.     * @var    array
  61.     */
  62.     var $moduleGroups = array();
  63.     
  64.     /**
  65.     * Central module parsing function.
  66.     *
  67.     * @param    array   Array of parsing data
  68.     * @return   array
  69.     * @see      analyseModuleDoc()
  70.     */
  71.     function analyseModule($para) {
  72.         
  73.         $module = $this->analyseModuleDoc($para["modules"]);
  74.         unset($para["modules"]);
  75.  
  76.         $this->moduleGroups[$module["group"]][] = $module["name"];
  77.  
  78.         reset($para["functions"]);
  79.         while (list($k, $data) = each($para["functions"]))
  80.             $module["functions"][strtolower($data["name"])] = $this->analyseFunction($data);
  81.         unset($para["functions"]);
  82.             
  83.         reset($para["consts"]);
  84.         while (list($k, $data) = each($para["consts"]))
  85.             $module["consts"][strtolower($data["name"])] = $this->analyseConstant($data);
  86.         unset($para["const"]);
  87.         
  88.         reset($para["uses"]);
  89.         while (list($k, $data) = each($para["uses"]))
  90.             $module["uses"][strtolower($data["file"])] = $this->analyseUse($data);
  91.         
  92.         return $module;
  93.     } // end func analyseModule
  94.     
  95.     /**
  96.     * Extracts the allowed documentation tags out of a module doc comment.
  97.     * 
  98.     * @param    array   Module paragraph
  99.     * @return   array
  100.     */
  101.     function analyseModuleDoc($para) {
  102.     
  103.         $module = $this->emptyModule;
  104.         $module["name"] = ("" != $para["name"]) ? $para["name"] : $this->currentFile;
  105.         $module["group"] = ("" != $para["group"]) ? $para["group"] : $this->currentFile;
  106.         
  107.         if ("missing" == $para["status"]) {
  108.             
  109.             $msg = "The file '$this->currentFile' does not contain any classes and seems to lack a module doc comment.";
  110.             $this->warn->addDocWarning($this->currentFile, "module", $module["name"], $msg, "missing");
  111.             
  112.         } else if ("tags missing" == $para["status"]) {
  113.         
  114.             $msg = "The module doc comment does not contain a @module or @modulegroup tag, the module gets names: '$this->currentFile'";
  115.             $this->warn->addDocWarning($this->currentFile, "module", $module["name"], $msg, "missing");
  116.         
  117.         }
  118.         
  119.         if ("" != $para["doc"]) {
  120.             
  121.             $tags   = $this->getTags($para["doc"]);
  122.             $module = $this->analyseTags($tags, $module, $this->moduleTags);
  123.             
  124.             list($msg, $module) = $this->checkParserErrors($module, "module");
  125.             if ("" != $msg) 
  126.                 $this->warn->addDocWarning($this->currentFile, "module", $module["name"], $msg, "mismatch");
  127.             
  128.             list($shortdesc, $fulldesc) = $this->getDescription($para["doc"]);            
  129.             $module["sdesc"] = $shortdesc;
  130.             $module["desc"]  = $fulldesc;
  131.         
  132.             $module["undoc"] = false;
  133.         }
  134.  
  135.         unset($module["module"]);
  136.         unset($module["modulegroup"]);
  137.         
  138.         return $module;
  139.     } // end analyseModuleDoc
  140.     
  141. } // end class PhpdocModuleParser
  142. ?>